Nice work @dgr! Thanks for taking so much care!

Some thoughts/ideas/observations:

Maybe docstrings could link to Etaoin user guide which in turn could link to https://wpt.fyi/results/webdriver/tests/classic/find_element_from_shadow_root/find.py?label=experimental&label=master&aligned in a prominent adoc NOTE. This way users would get a link to your very nice overview of the shadow dom (I read, I learned!) AND a link to current implementation limitations. Whaddya think?

Test-doc is failing because code blocks will return different results each time they are run. For example, this gets converted into a test:

(e/get-element-shadow-root driver {:id "shadow-root-host"})
;; => "ac5ab914-7f93-427f-a0bf-f7e91098fd37"

which expects a return of "ac5ab914-7f93-427f-a0bf-f7e91098fd37" always and will therefore fail.

Options:

1. Add a //:test-doc-blocks/skip before the code block to have test-doc-blocks skip the code block
2. Remove the ;; => lines from the code example, test-doc-block will only expect the code to run without exception and not expect a specific return. If you feel it important the reader of the doc see a typical return, you could instead express that in a comment or descriptive text outside of the code block
3. In some cases, consider rewriting the code sample, for example this:

   (e/query-shadow-root driver {:id "shadow-root-host"} {:css "#in-shadow"})
   ;; => "30fca382-6d4a-4f8a-9534-db76a1ed7cba"
   (e/get-element-text-el driver "30fca382-6d4a-4f8a-9534-db76a1ed7cba")
   ;; => "I'm in the shadow DOM"

   Could become:

   (->> (e/query-shadow-root driver {:id "shadow-root-host"} {:css "#in-shadow"})
        (e/get-element-text-el driver))
   ;; => "I'm in the shadow DOM"

I reviewed the user guide for what strategy I took for the element id returns, and it looks like I entirely avoided it in code blocks. It seems I spent a little bit of time upfront describing the difference between -el and non-el variants and didn't dwell on it at all later.

For me, it is a balance between "what does the reader need to see to understand this?" and "can I ensure that the code blocks should always work in the reader's REPL when they try them out?".

Anyhoo, great work, and I am happy to work out the above with you further.

OK, let me do one more commit with updates to doc strings and doc-test stuff.

OK, try it again.

Looks great @dgr, thanks!